Skip to main content

Best practice


Merchant and PayBy system interaction​

  1. The merchant’s server calls the order creation interface to request an order.
  2. The merchant’s server queries the order status.
  3. The merchant’s server receives payment notifications.

Before any payments can be processed, an order needs to be initiated by the merchant along with the merchant order number using Order creation API.

The merchant order number is generated by the merchant. It only supports the combination of letters, numbers, dashes (-) and underscores (_). PayBy requires the merchant order number to be unique for the same merchant (it is recommended to generate the order number according to the current system time plus a random sequence).

When an order is created, PayBy finishes the payment processing asynchronously and doesn't require the requester to hold on to a connection to wait. This gives more flexibility and for PayBy to serve more requests simultaneously, however, the requester doesn't immediately know the result of their payment as a side effect. To notify the merchant of the processing result, PayBy sends a notification to the merchant when payment has been processed or accepts a periodic query from the merchants to find out the latest state of the order. We will explain more in detail in the below sections.


Re-initiate a payment​

To re-initiate a payment, the original merchant order number should be used to avoid repeated payment. On the other hand, an order that has been paid or canceled cannot be re-opened. This is especially useful to offer clear traceability when it comes to audits or disputes.


When to retrieve an order?​

The query endpoint allows merchants to inquire about the status and details of all orders (pay, refund, transfer). Merchants can query the order status proactively and periodically using this API to determine the next step.

Even though PayBy tries everything possible to deliver a result notification, there are still cases where querying the order status is necessary and better, especially, in the following cases:

  1. The Merchant's server experiences regular maintenance and temporary outages of sorts so that a notification cannot be delivered.
  2. A system error or unknown transaction status is returned when calling the payment APIs.
  3. To confirm payment status before calling the Order creation API.

When to cancel (revoke) an order​

It is inevitable that some payments may fail or need to be re-initiated. As mentioned above, to keep the payment history clean and avoid duplicate payments, it's important for Merchants to follow the best practice and cancel an unfulfilled order when:

  1. During order creation, the request times out or didn't process successfully within an acceptable time window. It's always a good practice to query for the order status and cancel when it times out.
  2. Before re-initiate a new order before or after the above-mentioned timeout, it's recommended to cancel the previous one even though it may not have come through.
  3. After an order is created and pending payment from the user, the user might fail to proceed with the payment, e.g. accidentally declining, this would also require the merchant to cancel the order and create a new one.